Skip to content

Faster real-subspace GPU path: final complex signal from the kernel, one simulation per Jacobian - #58

Merged
mcencini merged 9 commits into
mainfrom
claude/project-thread-pqh402
Nov 12, 2026
Merged

mcencini merged 9 commits into
mainfrom
claude/project-thread-pqh402

Conversation

@mcencini

Copy link
Copy Markdown
Contributor

Requested by Matteo · project thread

What changed

  • The real-subspace kernels (forward and JVP, tile and layout) write each sample as interleaved complex64, multiplied by a complex factor per sample. That factor carries the sign the packing moves off the pulses and a simulator's constant receiver phase. Simulator.receiver (default 1) declares the receiver phase. MRF, MPRAGE and MPnRAGE set it to 1j instead of multiplying the signal in evaluate. Other paths apply the same factor in torch, and the native autograd function carries it through its JVP and VJP.
  • The turned flip and phase buffers are remembered per event stream, so the pulse-axis check is read once per stream and not on every call.
  • Tissue properties left at a plain number are filled on the device rather than copied from the host, which removes about 30 pageable copies per call.
  • jacobian() batches its directions under vmap, so the signal is simulated once and only the directional derivatives are taken per property.
  • The real forward kernel is capped at __launch_bounds__(64, 8).

No public return type changes. Matteo chose to keep the output complex.

Why

The aim is to match BlochSimulators.jl on the GPU. Profiling MRF-FISP on an A40 showed that a third of the forward was spent outside the kernel: a torch.complex pass, the 1j * multiply in MRFSimulator.evaluate, and host copies and syncs.

Validation

A40 (aleatico2), torch 2.13 + CUDA 12.9, MRF-FISP with 500 TRs, 32 states and 1e5 tissues, median of 30 calls:

build forward T1/T2 Jacobian
main ad0822f, sm_80 code 16.22 ms 86.18 ms
this branch, uncapped, sm_80 / sm_86 12.04 / 10.02 ms 56.97 / 56.27 ms
this branch, capped, sm_80 (shipped targets) 9.59 ms 54.80 ms
this branch, capped, sm_86 9.97 ms 56.23 ms
BlochSimulators.jl (real / complex states) 10.5 / 26 ms 36.6 ms

The signal checksum is identical in every build. A sweep over problems per thread (2, 4, 8), warps per block (2, 4, 8) and resident warps per SM found nothing faster than Y=8, 2 warps, 8 programs per SM, and every variant matched to 0 max error. With the cap, the 8.0 code runs faster on the A40 than an 8.6 build, so the build targets are unchanged.

After this PR, the forward is 99% kernel time. The Jacobian is still behind BlochSimulators.jl: its two dual-number passes take 18.9 ms each. Closing that gap needs a kernel that carries several directions in one sweep, which is left for a follow-up.

CPU, this container: pytest tests/ -n 4 gives 1661 passed, 325 skipped. The other failures are environment-only: a torchvision/torch mismatch (test_deepinv), an old mri-nufft (test_subspace_route), and test_an_image_quality_design_fits_in_its_budget, which failed under -n 4 but passes on its own. The host build of the GPU kernels passes test_host_kernels.py and test_real_subspace.py. New test: test_a_fingerprinting_sample_after_an_inversion_is_real_and_turned_by_the_flip (CPU and CUDA).

Documentation impact

None for callers: signals and their types are unchanged. Simulator.receiver is a new class attribute that a subclass can set.

Checklist

  • pytest tests/ passes locally, and a new test covers what changed.
  • ruff format and ruff check are clean.
  • Public functions and classes carry a numpydoc docstring.
  • Comments and docstrings describe the code as it is now.
  • A change to what the kernels compute is in both of them (tile and layout), and the host build checks the tile kernel against the CPU kernels.
  • bash scripts/build_docs.sh was not run.

Generated by Claude Code

…and sample sign folded in

The real kernels store each sample as an interleaved complex64 multiplied
by a per-sample complex factor, so the forward no longer makes a
torch.complex pass and a full-signal multiply after the kernel. A
simulator's constant receiver phase (1j for MRF, MPRAGE, MPnRAGE) and the
sign the packing moves off the pulses reach the kernel as that factor.
The turned flip and phase buffers are remembered per stream, so the
pulse-axis check is read once rather than on every call.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MFB6QP4KCaPBFdw9c6SoRd
…e on the device

The Jacobian batches its directions under vmap, so the signal is simulated
once and only the directional derivatives are taken per property. Tissue
properties left at a plain number are filled on the device rather than
copied from the host one by one.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MFB6QP4KCaPBFdw9c6SoRd
With the real forward kernel capped, the 8.0 code is the faster one on an
8.6 card, so a separate 8.6 or 8.9 build buys nothing.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MFB6QP4KCaPBFdw9c6SoRd
@mcencini
mcencini merged commit 22ce252 into main Nov 12, 2026
35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants